<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Theron: Theron::Actor::Send</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">Theron
   &#160;<span id="projectnumber">6.00.02</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceTheron.html">Theron</a></li><li class="navelem"><a class="el" href="classTheron_1_1Actor.html">Actor</a></li>  </ul>
</div>
</div><!-- top -->
<div class="contents">
<table cellspacing="0" cellpadding="0" border="0">
  <tr>
   <td valign="top">
      <div class="navtab">
        <table>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a3da98155747d33d767fe12b8b8c13aac.html#a3da98155747d33d767fe12b8b8c13aac">DeregisterHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a268613b27d2d718b55e2eb489118aa04.html#a268613b27d2d718b55e2eb489118aa04">GetAddress</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_afe30f86e99ff80691ec11e207711a46a.html#afe30f86e99ff80691ec11e207711a46a">GetFramework</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a4f6af5dba4b36bbb55ee216589ccfb63.html#a4f6af5dba4b36bbb55ee216589ccfb63">GetNumQueuedMessages</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a8b85886531b76f0e6aa9b46004ff6bb0.html#a8b85886531b76f0e6aa9b46004ff6bb0">IsHandlerRegistered</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindexHL" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a752faea0ecbb7f9525c02ed1ef19cbaf.html#a752faea0ecbb7f9525c02ed1ef19cbaf">SetDefaultHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_ab8806dfed72869b22d966968340268c3.html#ab8806dfed72869b22d966968340268c3">SetDefaultHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a8ad74c59dded739fd71a66b96bc79ea8.html#a8ad74c59dded739fd71a66b96bc79ea8">TailSend</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a95ce244d6cd6f4f3bfaea29dfb89ab6c.html#a95ce244d6cd6f4f3bfaea29dfb89ab6c">~Actor</a></td></tr>
        </table>
      </div>
   </td>
   <td valign="top" class="mempage">
<a class="anchor" id="a47c64d58a7a683b34101002989d7de0a"></a>
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;class ValueType &gt; </div>
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">bool Theron::Actor::Send </td>
          <td>(</td>
          <td class="paramtype">const ValueType &amp;&#160;</td>
          <td class="paramname"><em>value</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="classTheron_1_1Address.html">Address</a> &amp;&#160;</td>
          <td class="paramname"><em>address</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td> const</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">protected</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Sends a message to the entity (actor or <a class="el" href="classTheron_1_1Receiver.html" title="A standalone entity that can accept messages sent by actors. ">Receiver</a>) at the given address. </p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Responder : <span class="keyword">public</span> <a class="code" href="classTheron_1_1Actor.html">Theron::Actor</a></div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keyword">struct </span>Message</div>
<div class="line">    {</div>
<div class="line">    };</div>
<div class="line"></div>
<div class="line">    <span class="keyword">explicit</span> Responder(<a class="code" href="classTheron_1_1Framework.html">Theron::Framework</a> &amp;framework) : Theron::<a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a>(framework)</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a>(<span class="keyword">this</span>, &amp;Responder::Respond);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line"><span class="keyword">private</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keywordtype">void</span> Respond(<span class="keyword">const</span> Message &amp;message, <span class="keyword">const</span> <a class="code" href="classTheron_1_1Address.html">Theron::Address</a> from)</div>
<div class="line">    {</div>
<div class="line">        <span class="comment">// Send the message back to the sender.</span></div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a>(message, from);</div>
<div class="line">    }</div>
<div class="line">};</div>
</div><!-- fragment --><p>Any copyable class or Plain-Old-Data type can be sent in a message. Messages are copied when they are sent, so that the recipient sees a different piece of memory with the same value. The copying is performed with the copy-constructor of the message class.</p>
<dl class="section note"><dt>Note</dt><dd>The requirements for messages sent to remote actors over a network are different, and significantly stricter. Currently, message types sent to remote actors must be bitwise-copyable via memcpy, so can't contain pointers.</dd></dl>
<p>Typically non-POD message classes should be provided with a meaningful default constructor, copy constructor, assignment operator and destructor. If the message type is derived from a base type (in an inheritance hierarchy of message types) then the base class should typically have a virtual destructor.</p>
<p>In general it is unsafe to pass pointers in messages, since doing so re-introduces shared memory, where multiple actors can access the same memory at the same time. The exception is where steps are taken to ensure that the sender is prevented from accessing the referenced memory after the send (for example using an auto-pointer). In such cases ownership is effectively transferred to the recipient by the message.</p>
<p>Note that immediate C arrays can't be sent as messages, since they aren't copyable. For example the first call to Send in the following code won't compile, because the literal string message is an array. The second, where the array is sent as a pointer instead, works fine. Arrays can safely be sent as members of message classes. Of course, a safer approach is to send a std::string, as shown as the final call:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span><a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a> : <span class="keyword">public</span> <a class="code" href="classTheron_1_1Actor.html">Theron::Actor</a></div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keyword">struct </span>Message</div>
<div class="line">    {</div>
<div class="line">        <span class="keywordtype">char</span> mBuffer[32];</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    <span class="keyword">explicit</span> <a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a>(<a class="code" href="classTheron_1_1Framework.html">Theron::Framework</a> &amp;framework) : Theron::<a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a>(framework)</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a>(<span class="stringliteral">&quot;hello&quot;</span>, someAddress);                 <span class="comment">// Immediate C array; won&#39;t compile!</span></div>
<div class="line"></div>
<div class="line">        <span class="keywordtype">char</span> *<span class="keyword">const</span> message(<span class="stringliteral">&quot;hello&quot;</span>);</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a>(message, someAddress);                 <span class="comment">// Fastest, but use with care!</span></div>
<div class="line"></div>
<div class="line">        Message message2;</div>
<div class="line">        strcpy(message2.mBuffer, <span class="stringliteral">&quot;hello&quot;</span>);</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a>(message2, someAddress);                <span class="comment">// Safe but involves a shallow copy.</span></div>
<div class="line"></div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a>(std::string(<span class="stringliteral">&quot;hello&quot;</span>), someAddress);    <span class="comment">// Safest but involves a deep copy.</span></div>
<div class="line">    }</div>
<div class="line">}</div>
</div><!-- fragment --><p>The boolean return value returned by Send indicates whether the message was delivered. Note however that messages sent to actors are in reality addressed to mailboxes, not actors themselves. So a return value of true indicates only that the message was delivered to a mailbox, which may well be unattended.</p>
<p>A return value of false indicates that an error occurred and the message was not sent. In the case of messages addressed to a <a class="el" href="classTheron_1_1Receiver.html" title="A standalone entity that can accept messages sent by actors. ">Receiver</a>, this may indicate that no such receiver is registered (it may have existed once and been destructed). In the case of messages addressed to an actor, a false return value more likely indicates that the message could not be allocated, due to out-of-memory.</p>
<p>An important subtlety is that a return value of true indicates only that the message was delivered to a mailbox, not that it was delivered to an associated actor, or moreover that the receiving actor had message handlers registered for it. On the contrary a true return value indicates only that the message was delivered to a mailbox.</p>
<p>The processing of the mailbox is scheduled asynchronously and typically happens some time later, on a different thread. If no actor is registered at the mailbox when it is eventually processed, then the message will simply be discarded, even though it was delivered successfully to the mailbox. And even if an actor is registered at the mailbox, it may have no handlers registered for the message type, in which case the message may be silently discarded.</p>
<p>Such undelivered or unhandled messages will be caught and reported as asserts by the default fallback handler, unless it is replaced by a custom user implementation using <a class="el" href="classTheron_1_1Framework_a43f84e854ced9bc9df593ffcd61d2ffd.html#a43f84e854ced9bc9df593ffcd61d2ffd">Framework::SetFallbackHandler</a>.</p>
<p>Messages sent to mailboxes within the local process by the same sender are guaranteed to be delivered to those mailboxes in the order they are sent. Once delivered, they are guaranteed to processed in the order they were received. When messages by different senders or to mailboxes in other processes (potentially on other hosts) the arrival order is not guaranteed.</p>
<p>This method can safely be called within the constructor or destructor of a derived actor object, as well as (more typically) within its message handler functions.</p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">ValueType</td><td>The message type (any copyable class or Plain-Old-Data type). </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">value</td><td>The message value to be sent. </td></tr>
    <tr><td class="paramname">address</td><td>The address of the destination <a class="el" href="classTheron_1_1Receiver.html" title="A standalone entity that can accept messages sent by actors. ">Receiver</a> or <a class="el" href="classTheron_1_1Actor.html" title="The actor baseclass. ">Actor</a> mailbox. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>True, if the message was delivered, otherwise false. </dd></dl>

</div>
</div>
    </td>
  </tr>
</table>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
